Welcome back. Let's take a look at another REST API, iTunes.
iTunes is Apple's media store.
The REST API lets us make queries asking what's in the store.
So, this page is their documentation.
There's a base URL,
which goes up through search, so https://itunes.apple.com/search.
Then, as we've seen before, the query parameters,
there is a question mark and then some key value pairs.
What are the keys and values that iTunes understands,
for those query parameters?
Let's scroll down and we'll see.
We've got a whole table of them, there's a bunch.
In the left column, are the key names,
things like term, country, media or entity.
In the right column,
there's some information about what are the allowable values.
So, the term that's going to be what we're searching for,
and you can put any text string in there,
but for media, there's only certain allowable values like movie or podcasts or music.
So in our URL, when we make a request to iTunes,
we're going to have something like media equals podcast.
The other two columns tell us whether we are required to include this query parameter.
Yes, you have to include term and you have to include country,
but the other ones are optional.
Then, there's just a description that gives you some hints about what you getting.
So, let's try to figure out what we would pass in for
the params dictionary when we make a call to request.get.
I'm going to go back to Runestone and we'll come
back and look at this documentation as we need it.
In the textbook, we've got a couple of exercises.
Suppose we are trying to look for podcasts originating in Ann Arbor,
and we're going to pass in a params dictionary to request that get.
What value should we put here as the value associated with term?
So, this is the thing we're searching for.
So, since we've said we're looking for podcasts that mention Ann Arbor,
then we put in Ann Arbor in here,
and check me and it says,
"Oh, don't forget the quotes.
It needs to be a string."
We're going to be putting a value here and it's got to be a string.
So, let's put that value in quotes.
When it gets encoded into the URL,
it won't have the quotes around it.
But in order to be a value in this params dictionary,
it does need the quotes.
That's all good.
So, let's look at our next question.
There's another parameter.
If we're searching for podcasts,
we're going to have to give another query parameter whose value is going to be podcast,
which query parameter is it?
Well, you could try to guess,
and perhaps you remember the documentation page but let's go look.
It turns out, we can say podcast for the query parameter media.
If we scroll down a little farther,
it turns out we also can say entity equals podcast.
If we say media equals podcast,
then we'll be doing a little bit broader search.
We can do a slightly narrower search,
where we say entity equals podcast and that will be
limited to searching for Ann Arbor in the podcast title,
excluding looking for it where Ann Arbor as part of the author.
So, we could say either media or entity.
We've actually set this up so that it will accept either media and says,
yes you can use that.
But in our code below, we're going to use entity.
So, entity is also okay.
So, here's a request that we can make.
We're using requests with caching rather than requests just to
make sure that if there's any problems getting to iTunes on a particular day,
that it'll still work.
We're passing in, term Ann Arbor and entity podcast.
It'll take us a minute and we'll get a result.
It found it in the permanent cache.
Now, we haven't chosen to do anything with this,
but I could also, for example,
print what the full URL was that was created,
and that's this URL.
Now because we use caching,
it didn't actually go and make the request
itunes.apple.com but this is the request it would've made.
It got the saved results,
the cached results for that URL.
Now, at this point, I've loaded
the response text into
a Python object and I had saved that in the variable called py data.
At this point, we would have to go through our usual understand, extract,
repeat process to pull out the data that we want from whatever is in py data.
I'm going to skip ahead because I've already done
that process of doing the understand extract and repeat and this is what I got to.
So, I found that the top-level object was a dictionary.
It had a key called results,
and I've extracted the value associated with results.
That value is a list.
It's a list of dictionaries,
one dictionary for each podcast result.
Each of those podcasts is a dictionary that has a key called track name,
and I've extracted the track name.
So, when I run this,
I will get the names of podcasts that have the word
and I'll print them.
So, it's telling us that it founded in permanent cache and
then on each line we have one track name.
As you can see, there's one from the Ann Arbor District Library.
The award winning Ann Arbor District Library, I should say.
We love our library in Ann Arbor,
and we love libraries in general at the School of Information,
and there's a bunch of podcasts from churches.
You can see the Harvest Mission Community Church,
Grace Bible Church and so on.
Actually, there's a few more podcasts from the Ann Arbor District Library.
So, that's an example of deciphering the iTunes API documentation,
and using it to construct REST API queries.
We'll see you next time.